import { PackageManagerTabs } from '@theme';

# Modern.js Module

This section introduces how to migrate a project using Modern.js Module to Rslib.

## Adapt package.json

`Rslib` has a minimal dependency footprint. For the basic functionality you only need the package `@rslib/core`.

You can create a new Rslib project by following the [Quick Start](/guide/start/quick-start) to see the `package.json` file. Then update your existing `package.json` file like below:

- Remove the fields `main`, `lint-staged`, `simple-git-hooks`, `sideEffects` and `publishConfig`
- Change the `types` field from `./dist/types/index.d.ts` to `./dist/index.d.ts`
- Change the `module` field from `./dist/es/index.js` to `./dist/index.js`
- Remove the scripts fields `prepare`, `build:watch`, `reset`, `change`, `bump`, `pre`, `change-status`, `gen-release-note`, `release`, `new`, `upgrade`
- Change the script `build` from `modern build` to `rslib build`
- Change the script `dev` from `modern dev` to `rslib build --watch`
- Change the script `lint` name to `check` and keep the value
- Add a new script `format` with the value `biome format --write`
- Add the script `test` with the value `vitest run`
- Add the field `exports` (object)
  - Add the field `"."` (object)
  - Add the fields `"types": "./dist/index.d.ts"` and `"import": "./dist/index.js"`
- Add the field `files` with the value `["dist"]`
- Depending on your configuration and use-case the `devDependencies` can vary
  - It is important to replace `@modern-js/module-tools` with `@rslib/core`
  - We do not need `rimraf`, `lint-staged` and `simple-git-hooks` anymore for starters
- Copy over your required `dependencies` and `peerDependencies` if needed

Your `package.json` should look something like this:

```json title="package.json"
{
  "name": "rslib",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  },
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "rslib build",
    "check": "biome check --write",
    "dev": "rslib build --watch",
    "format": "biome format --write",
    "test": "vitest run"
  },
  "devDependencies": {
    "@biomejs/biome": "^1.9.3",
    "@rslib/core": "^0.1.3",
    "typescript": "^5.6.3",
    "vitest": "^2.1.8"
  },
  "peerDependencies": {},
  "dependencies": {}
}
```

## Adapt bundler config

Now we have a clean slate to work with. We will continue with the `Rslib` configuration. It follows the same pattern as all `Rs*` projects. Since this step is very unique for every environment, below is an basic example:

Replace your `modern.config.ts` with a `rslib.config.ts`:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  source: {
    entry: {
      index: ['./src/**'],
    },
  },
  lib: [
    {
      bundle: false,
      dts: true,
      format: 'esm',
    },
  ],
});
```

## TypeScript declaration

If you use TypeScript in your `Modern.js Module` and need to generate declaration files, add the following changes:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  //...
  lib: [
    {
      //...
      dts: true,
    },
  ],
});
```

## React

If you use React in your `Modern.js Module`, add the following changes:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
// Quick tip: You can use all Rsbuild plugins here since they are compatible with Rslib
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  //...
  output: {
    target: 'web',
  },
  plugins: [pluginReact()],
});
```

In addition, you have to install the `@rsbuild/plugin-react` package as `devDependencies`.

<PackageManagerTabs command="add @rsbuild/plugin-react -D" />

## Sass

If you use Sass in your `Modern.js Module`, add the following changes:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
// Quick tip: You can use all Rsbuild plugins here since they are compatible with Rslib
import { pluginSass } from '@rsbuild/plugin-sass';

export default defineConfig({
  //...
  plugins: [pluginSass()],
});
```

In addition, you have to install the `@rsbuild/plugin-sass` package as `devDependencies`.

<PackageManagerTabs command="add @rsbuild/plugin-sass -D" />

If you run TypeScript together with Sass, you might run into declaration files generation errors. This can be resolved by adding a `env.d.ts` file in your `/src` directory.

```ts title="src/env.d.ts"
declare module '*.scss' {
  const content: { [className: string]: string };
  export default content;
}
```

or

```ts title="src/env.d.ts"
/// <reference types="@rslib/core/types" />
```

## CSS Modules

If you use CSS Modules in your `Modern.js Module`, add the following changes:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
import { pluginSass } from '@rsbuild/plugin-sass';

export default defineConfig({
  lib: [
    {
      //...
      output: {
        cssModules: {
          // the CSS Modules options are 1:1 the same as in the official "css-modules" package
          localIdentName: '[local]--[hash:base64:5]',
        },
      },
    },
  ],
  plugins: [pluginSass()],
});
```

## Contents supplement

This migration doc is contributed by community user [YanPes](https://github.com/YanPes). Much appreciation for his contribution!

Rslib is designed to be the next generation solution of Modern.js Module, and we will provide detailed configuration mapping documentation as well as feature migration guides and scripts in the second quarter of 2025.
